<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
<html>
<head>
<title>The Perl DBI</title>
<link rel="stylesheet" href="/cfg/format.css" type="text/css">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="keywords" content="SQLite, Perl, DBI, tutorial, database, 
programming, development">
<meta name="description" content="In this chapter of the SQLite Perl tutorial, 
we present the Perl DBI module and the SQLite database.">
<meta name="language" content="en">
<meta name="author" content="Jan Bodnar">
<meta name="distribution" content="global">

<script type="text/javascript" src="/lib/jquery.js"></script>
<script type="text/javascript" src="/lib/common.js"></script>

</head>

<body>

<div class="container">

<div id="wide_ad" class="ltow">
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* 160x600, August 2011 */
google_ad_slot = "2484182563";
google_ad_width = 160;
google_ad_height = 600;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<div class="content">


<a href="/" title="Home">Home</a>&nbsp;
<a href="..">Contents</a>


<h1>Perl DBI</h1>


<p>
In the first chapter of the SQLite Perl tutorial, we will introduce the
Perl DBI module and the SQLite database. We will provide some definitions 
and show how to install the necessary elements. 
</p>

<div class="center">
<script type="text/javascript"><!--
google_ad_client = "ca-pub-9706709751191532";
/* top_horizontal */
google_ad_slot = "3327173442";
google_ad_width = 468;
google_ad_height = 60;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>


<h2>Prerequisites</h2>


<p>
To work with this tutorial, we must have Perl language, SQLite database,
sqlite3 command line tool, Perl DBI and DBD::SQLite modules installed.
The DBI is the standard Perl database interface. Each database has its driver.
In our case, DBD::SQLite is the driver for the SQLite database. 
</p>

<pre>
$ sudo perl -MCPAN -e shell
cpan> install DBI
cpan[2]> install DBD::SQLite
</pre>

<p>
The above commands show, how to install Perl DBI and DBD::SQLite
modules.
</p>

<h2>SQLite database</h2>

<p>
SQLite is an embedded relational database engine. It is a self-contained, 
serverless, zero-configuration and transactional SQL database engine.
SQLite implements most of the SQL-92 standard for SQL. The SQLite engine is not a standalone process. 
Instead, it is statically or dynamically linked into the application. 
An SQLite database is a single ordinary disk file that can be located 
anywhere in the directory hierarchy.
</p>

<p>
The SQLite comes with the sqlite3 command line utility. It can be used to
issue SQL commands against a database. Now we are going to use the sqlite3 command 
line tool to create a new database. 
</p>

<pre>
$ sqlite3 test.db
SQLite version 3.6.22
Enter ".help" for instructions
Enter SQL statements terminated with a ";"
</pre>

<p>
We provide a parameter to the sqlite3 tool. The test.db is a 
database name. It is a single file on our disk. If it is present, 
it is opened. If not, it is created. 
</p>


<pre>
sqlite> .tables
sqlite> .exit
$ ls
test.db
</pre>

<p>
The <code>.tables</code> command gives a list of tables in the test.db
database. There are currently no tables. The <code>.exit</code> command
terminates the interactive session of the sqlite3 command line tool. 
The ls Unix command shows the contents of the current working directory. 
We can see the test.db file. All data will be stored in this single file.
</p>


<h2>Perl DBI</h2>

<p>
The Perl <b>DBI</b> (Database Interface) is a database access module for
the Perl programming language. It defines a set of methods, variables and
conventions that provide a standard database interface. The DBI is also 
responsible for the dynamic loading of drivers, error checking and handling, 
providing default implementations for methods, and many other non-database 
specific duties. The DBI dispatches method calls to the appropriate database 
driver. The <b>DBD</b> (Database Driver) is a Perl module which translates 
the DBI methods for a specific database engine. The database drivers are supplied by database
vendors. 
</p>

<pre class="code">
#!/usr/bin/perl

use strict;
use DBI;

my @ary = DBI->available_drivers();
print join("\n", @ary), "\n";
</pre>

<p>
The code example lists all available drivers on our system. 
</p>

<pre class="explanation">
use DBI;
</pre>

<p>
We import the DBI module for our script. 
</p>

<pre class="explanation">
my @ary = DBI->available_drivers();
</pre>

<p>
The <code>available_drivers()</code> class method gets all the 
current available drivers on our system.  
</p>

<pre class="explanation">
print join("\n", @ary), "\n";
</pre>

<p>
This line prints the drivers to the console, each on a separate
line. 
</p>

<pre>
$ ./available_drivers.pl
DBM
ExampleP
File
Gofer
Proxy
SQLite
Sponge
mysql
</pre>

<p>
Example output.
</p>

<h2>Common DBI methods</h2>

<p>
The following table lists some common DBI methods.
</p>

<table>
<tr class="hdr"><th>Method name</th><th>Description</th></tr>
<tr><td>available_drivers()</td><td>Returns a list of all available drivers</td></tr>
<tr class="gray"><td>connect()</td><td>Establishes a connection to the requested data source</td></tr>
<tr><td>disconnect()</td><td>Disconnects from the database server</td></tr>
<tr class="gray"><td>prepare()</td><td>Prepares an SQL statement for execution</td></tr>
<tr><td>execute()</td><td>Executes the prepared statement</td></tr>
<tr class="gray"><td>do()</td><td>Prepares and executes an SQL statement</td></tr>
<tr><td>bind_param()</td><td>Associates a value with a placeholder in a prepared statement</td></tr>
<tr class="gray"><td>bind_col()</td><td>Binds a Perl variable to an output field of a SELECT statement</td></tr>
<tr><td>begin_work()</td><td>Starts a new transaction</td></tr>
<tr class="gray"><td>commit()</td><td>Writes the most recent series of uncommitted database changes to the database</td></tr>
<tr><td>rollback()</td><td>Undoes the most recent series of uncommitted database changes</td></tr>
<tr class="gray"><td>quote()</td><td>Quotes a string literal for use as a literal value in an SQL statement</td></tr>
<tr><td>dump_results()</td><td>Fetches all the rows and prints them</td></tr>
<tr class="gray"><td>fetchrow_array()</td><td>Fetches the next row as an array of fields</td></tr>
<tr><td>fetchrow_arrayref()</td><td>Fetches the next row as a reference array of fields</td></tr>
<tr class="gray"><td>fetchrow_hashref()</td><td>Fetches the next row as a reference to a hashtable</td></tr>
<tr><td>fetchall_arrayref()</td><td>Fetches all data as an array of arrays</td></tr>
<tr class="gray"><td>finish()</td><td>Finishes a statement and lets the system free resources</td></tr>
<tr><td>rows()</td><td>Returns the number of rows affected</td></tr>
<tr class="gray"><td>column_info()</td><td>Provides information about columns</td></tr>
<tr><td>table_info()</td><td>Provides information about tables</td></tr>
<tr class="gray"><td>primary_key_info()</td><td>Provides information about primary keys in tables</td></tr>
<tr><td>foreign_key_info()</td><td>Provides information about foreign keys in tables</td></tr>
</table>

<h2>Conventions</h2>

<p>
Perl programmers usually use the following variable names when working with Perl DBI. 
In this tutorial we will adhere to these conventions too. 
</p>

<table>
<tr class="hdr"><th>Variable name</th><th>Description</th></tr>
<tr><td>$dbh</td><td>Database handle object</td></tr>
<tr class="gray"><td>$sth</td><td>Statement handle object</td></tr>
<tr><td>$drh</td><td>Driver handle object (rarely seen or used in applications)</td></tr>
<tr class="gray"><td>$h</td><td>Any of the handle types above ($dbh, $sth, or $drh)</td></tr>
<tr><td>$rc</td><td>General Return Code  (boolean: true=ok, false=error)</td></tr>
<tr class="gray"><td>$rv</td><td>General Return Value (typically an integer)</td></tr>
<tr><td>@ary</td><td>List of values returned from the database, typically a row of data</td></tr>
<tr class="gray"><td>$rows</td><td>Number of rows processed (if available, else -1)</td></tr>
<tr><td>$fh</td><td>A filehandle</td></tr>
<tr class="gray"><td>undef</td><td>NULL values are represented by undefined values in Perl</td></tr>
<tr><td>\%attr</td><td>Reference to a hash of attribute values passed to methods</td></tr>
</table>


<p>
This chapter of the SQLite Perl tutorial was an introduction to the Perl DBI module and 
the SQLite database.
</p>

<div class="botNav, center">
<span class="botNavItem"><a href="/">Home</a></span> ‡ <span class="botNavItem"><a href="..">Contents</a></span> ‡ 
<span class="botNavItem"><a href="#">Top of Page</a></span>
</div>


<div class="footer">
<div class="signature">
<a href="/">ZetCode</a> last modified April 8, 2012  <span class="copyright">&copy; 2007 - 2013 Jan Bodnar</span>
</div>
</div>

</div> <!-- content -->

</div> <!-- container -->

</body>
</html>

